home *** CD-ROM | disk | FTP | other *** search
/ Floppyshop 2 / Floppyshop - 2.zip / Floppyshop - 2.iso / diskmags / 0022-3.564 / dmg-0055 / 595.txt < prev    next >
Text File  |  1997-04-16  |  22KB  |  470 lines
  1. Today's Topics:
  2.                  GEMDOS Extended Argument Spec (LONG)
  3. ----------------------------------------------------------------------
  4.  
  5. Date: 1 Nov 89 19:18:30 GMT
  6. From: imagen!atari!kbad@ucbvax.Berkeley.EDU  (Ken Badertscher)
  7. Subject: GEMDOS Extended Argument Spec (LONG)
  8.  
  9. GEMDOS EXTENDED ARGUMENT (ARGV) SPECIFICATION
  10.  
  11. Introduction
  12.  
  13. The Pexec() function of GEMDOS allows a program to pass to a child
  14. process a command line up to 125 characters long, with arguments
  15. separated by spaces.  No provision is made in GEMDOS for the child to
  16. know its own name.  This makes it difficult for C programs to correctly
  17. fill in argv[0], the standard place where a C program finds the command
  18. which invoked it.  Because the command line arguments are separated by
  19. spaces, it is difficult to pass an argument with an embedded space.
  20. This document will specify a method of passing arguments which allows
  21. arbitrary argument length, embedded spaces, and support for argv[0].
  22.  
  23. Standard Argument Passing
  24.  
  25. The Pexec Cookbook specifies how to use Pexec() to launch a child
  26. process, passing a command tail (argument string) and an environment.
  27. Before getting into the extended argument scheme, let's review how
  28. arguments are normally passed to a child.
  29.  
  30. A parent process builds a command line into an argument string - a null
  31. terminated string whose first byte contains the length of the rest of
  32. the string - and its address is passed as one of the arguments to
  33. Pexec().  GEMDOS copies this argument string to the basepage which it
  34. creates for the child.  Thus the parent is responsible for gathering
  35. all the child's arguments into one string.  This is normally handled by
  36. a library exec() function.  The child is responsible for parsing the
  37. string of space-separated arguments back into an array of strings.
  38. This parsing is normally handled by the child's startup code.
  39.  
  40. Evolution
  41.  
  42. Several methods of bypassing the limits imposed by Pexec() have been
  43. used by GEMDOS programs.  Some allow a user to specify a file on the
  44. command line which contains the rest of the arguments.  Others get a
  45. pointer to the arguments, or the arguments themselves, from the
  46. environment string.  Most MS-DOS programs use a command file for the
  47. extra arguments.  This can be inconvenient for a user, cluttering the
  48. file system with command files, and making the operation of batch files
  49. and makefiles more confusing.
  50.  
  51. Several "standards" have arisen on the ST which use the environment to
  52. pass arguments.  While more convenient than command files, these
  53. standards have other problems.  Some rely on sharing memory between
  54. parent and child processes.  Some take advantage of undocumented
  55. features of the operating system to get argv[0].  Others give the
  56. child process no way to validate that the arguments it finds are
  57. intended for it.
  58.  
  59. Rationale
  60.  
  61. In order to pass more than the standard 125 characters worth of
  62. arguments to a child, or to let the child find its name, the parent
  63. must place the extra information in a place where the child can access
  64. it safely and legally.  The most convenient place is in the child's
  65. environment string.  An environment string is a series of
  66. null-terminated strings of the format "VARIABLE=value" (e.g.
  67. PATH=c:\bin,c:\etc, or ShellP=YES).   The last null-terminated string
  68. in the environment is followed by a zero byte, thus two consecutive
  69. nulls indicates the end of the environment.   The environment is
  70. allocated for the child by GEMDOS, it is owned by the child, and its
  71. contents can be specified by the parent.
  72.  
  73. The child must have some way of knowing that the arguments which
  74. it finds in its environment are intended for it.  The child may have
  75. been invoked by a parent which does not conform to this specification.
  76. Such a parent would leave _its_ arguments in the environment, and could
  77. pass that environment on to the child.  The child would mistakenly
  78. interpret its parent's arguments as its own.
  79.  
  80. Placing arguments in the environment passed to the child gets around
  81. all of the command line limits of the standard Pexec() command tail.
  82. Because there is no limit on the length of the environment, arbitrary
  83. length arguments are supported.  Arguments placed in the environment
  84. are null terminated, so they may contain spaces.  A parent can also
  85. place the name of the command with which it invokes the child in the
  86. child's environment, providing support for argv[0].  Validation of the
  87. extended arguments can be placed in the standard Pexec() command line,
  88. by assigning a special meaning to an invalid length byte.
  89.  
  90. The GEMDOS Extended Argument Specification
  91.  
  92. This specification uses the convention that the presence of an
  93. environment variable named ARGV (all upper case) indicates that extended
  94. arguments are being passed to the child in its environment.  This means
  95. that ARGV is a "boolean" environment variable.  For the purpose of this
  96. specification, its value is not significant, but its presence indicates
  97. that the strings following it are the arguments for the child.
  98. Implementations of this specification are free to give the ARGV
  99. environment variable any value.  The ARGV environment variable must be
  100. the last one in the environment passed to the child, so that the child
  101. can truncate its environment at that point, and treat everything before
  102. the ARGV as environment, and everything after it as arguments.
  103.  
  104. The first argument to the child (argv[0]) is the first string in the
  105. environment after the ARGV variable.  This argument is the "pathname"
  106. parameter passed by the parent to Pexec().  The remaining arguments are
  107. those that the child would normally find in the command tail in its
  108. basepage.  Even if all of the arguments would normally fit in a child's
  109. command tail, the parent should set up the arguments in the environment
  110. to take advantage of the benefits of this extended argument scheme.
  111.  
  112. As many arguments as will fit in the command tail will be passed there
  113. as well as in the environment, to support non-conforming programs.  As
  114. a flag that arguments are also in the environment, the length byte of
  115. the command tail will be 127 (hex 7f).  Non-conforming programs should
  116. not have a problem with this length byte, because it is longer than the
  117. maximum 125 bytes allowed by Pexec().
  118.  
  119. As an aside, the Pexec Cookbook erroneously implies that a command line
  120. can be 126 or 127 characters long.  In fact, GEMDOS only copies to the
  121. child's basepage up to 125 bytes, or until it encounters a null, from
  122. the argument string passed to Pexec().  It ignores the length byte,
  123. placing a null at the same place it found one or at the 126th byte if
  124. no null is found.  This has several implications: the length byte is
  125. not validated by GEMDOS (necessitating validation in the child's
  126. startup code, but also making this extended argument spec possible),
  127. and the null terminator _can_ be located after the end of the real
  128. command tail (the Desktop places a CR character after the command tail
  129. and before the null).  The ARGSTART.S startup code listing below
  130. demonstrates how to correctly validate and parse a GEMDOS command tail.
  131.  
  132. A child which finds an ARGV environment variable can use the command
  133. tail length byte value of 127 to validate that the arguments following
  134. the variable are valid, and not just left over from a non-conforming
  135. parent which left its own ARGV arguments in the environment.
  136.  
  137. Because the strings in the environment following an ARGV variable are
  138. not environment variables, a child should truncate its own environment
  139. at the ARGV variable by changing the 'A' to a null.
  140.  
  141. Implementation: Parental Responsibilities
  142.  
  143. To pass arguments in the environment, a parent must create an
  144. environment string for the child.  This can be achieved by first
  145. allocating as much space as is used in the parent's own environment,
  146. plus enough room for the ARGV variable and the arguments to the child,
  147. and then copying the parent's environment to the newly allocated area.
  148. Next, the ARGV variable must be appended, since it must be the last
  149. variable in the child's environment string.  Following the ARGV variable
  150. is the null-terminated pathname of the child as passed to Pexec(), then
  151. the null-terminated arguments to the child, followed by a final null
  152. byte indicating the end of the environment.
  153.  
  154. After setting up the arguments in the environment, the parent must
  155. place as many arguments as it can fit in the command tail it passes
  156. to Pexec().  This way, a child which does not conform to this
  157. specification can still get arguments from the command tail in its
  158. basepage.  When placing arguments in the environment, the parent must
  159. set the first (length) byte of the command tail to 127 (hex 7f),
  160. validating the arguments in the environment.
  161.  
  162. Here is an example execv() library routine in C.  It uses three local
  163. utility routines, e_strlen(), e_strcpy(), and str0cpy() for getting
  164. environment size and copying strings into the environment created for
  165. the child.
  166.  
  167.  
  168. /* EXECV.C - example execv() library routine
  169.  * ================================================================
  170.  * 890910 kbad
  171.  */
  172.  
  173. long Malloc( long nbytes );
  174. long Pexec( short mode, char *filename, char *tail, char *env );
  175. long Mfree( void *address );
  176.  
  177. /* Return the total length of the characters and null terminators in
  178.  *   an array of strings.
  179.  * `strings' is an array of pointers to strings, with a null pointer
  180.  *   as the last element.
  181.  */
  182. static long
  183. e_strlen( char *strings[] )
  184. ?
  185.         char    *pstring;
  186.         long    length = 0;
  187.  
  188.     while( *strings != 0 ) ?        /* Until reaching null pointer,     */
  189.         pstring = *strings++;       /* get a string pointer,            */
  190.         do ?                        /* find the length of this string,  */
  191.             ++length;               /* using do-while to count the      */
  192.         ? while( *pstring++ != 0 ); /* null terminator.                 */
  193.     ?
  194.     return length;                  /* Return total length of all strings */
  195. ?
  196.  
  197. /* Copy a string, including the null terminator, and return a pointer
  198.  * to the end of the destination string.
  199.  */
  200. static char *
  201. str0cpy( char *dest, char *source )
  202. ?
  203.     do ? /* use do-while to include null terminator */
  204.         *dest++ = *source;
  205.     ? while( *source++ != 0 );
  206.     return dest;
  207. ?
  208.  
  209. /* Copy an array of strings into an environment string, and return a pointer
  210.  * to the end of the environment string.
  211.  * `strings' is an array of pointers to strings with a null pointer
  212.  *   as the last element.
  213.  * `envstring' points to the environment string.
  214.  */
  215. static char *
  216. e_strcpy( char *envstring, char *strings[] )
  217. ?
  218.     while( *strings != 0 ) ?
  219.         envstring = str0cpy( envstring, *strings );
  220.         ++strings;
  221.     ?
  222.     return envstring;               /* Return end of environment string */
  223. ?
  224.  
  225.  
  226. /* Run a program, passing it arguments according to the
  227.  * GEMDOS Extended Argument Spec.
  228.  *
  229.  * `childname' is the relative path\filename of the child to execute.
  230.  * `args' is an array of pointers to strings to be used as arguments
  231.  *   to the child.  The last array element must be a null pointer.
  232.  * `environ' is a global array of pointers to strings
  233.  *   which make up the caller's environment.
  234.  */
  235. long
  236. execv( char *childname, char *args[] )
  237. ?
  238.         long    envsize, ret;
  239.         char    *parg, *penvargs, *childenv, *pchildenv;
  240.         short   lentail;
  241.         char    argch, tail[128], *ptail;
  242. static  char    argvar[] = "ARGV=";
  243. extern  char    *environ[];
  244.  
  245. /*
  246.  * Find out how much memory we'll need for the child's environment
  247.  */
  248.     envsize = e_strlen( environ );      /* length of environment        */
  249.     envsize += e_strlen( args );        /* plus command tail args       */
  250. /* plus length of argv[0] */
  251.     parg = childname;
  252.     do ? /* use do-while to include null terminator */
  253.         ++envsize;
  254.     ? while( *parg++ != 0 );
  255. /* plus length of ARGV environment variable and final null */
  256.     envsize += 7;
  257.     envsize += envsize & 1; /* even # of bytes */
  258. /*
  259.  * Allocate and fill in the child's environment
  260.  */
  261.     ret = Malloc( envsize );
  262.     if( ret < 0 )
  263.         return ret; /* Malloc error */
  264.     childenv = (char *)ret;
  265.     pchildenv = e_strcpy( childenv, environ );   /* copy caller environment */
  266.     pchildenv = str0cpy( pchildenv, argvar );    /* append ARGV variable */
  267.     pchildenv = str0cpy( pchildenv, childname ); /* append argv[0] */
  268.     penvargs = pchildenv;                        /* save start of args */
  269.     pchildenv = e_strcpy( pchildenv, args );     /* append args */
  270.     *pchildenv = 0;                              /* terminate environment */
  271. /* put as much in the command tail as will fit */
  272.     lentail = 0;
  273.     ptail = &tail[1];
  274.     while( (lentail < 126) && (penvargs < pchildenv) ) ?
  275.         argch = *penvargs++;
  276.         if( argch == 0 ) ?
  277.             *ptail++ = ' ';
  278.         ? else ?
  279.             *ptail++ = argch;
  280.         ?
  281.     ?
  282. /* terminate command tail and validate ARGV */
  283.     *ptail = 0;
  284.     tail[0] = 127;
  285. /*
  286.  * Execute child, returning the return code from Pexec()
  287.  */
  288.     ret = Pexec( 0, childname, tail, childenv );
  289.     Mfree( childenv );
  290.     return ret;
  291. ?
  292. /* End of execv() example code */
  293.  
  294.  
  295. Implementation: Prenatal Responsibilities
  296.  
  297. A program's startup code must handle getting extended arguments out of
  298. the environment.  The startup code should get the basepage pointer off
  299. the stack, then get the environment pointer from the basepage, and
  300. search the environment for "ARGV=".  If "ARGV=" is found, the command
  301. line length byte in the basepage is checked.  If the command line
  302. length byte is 127, then the arguments in the environment are valid.
  303. The first argument begins after the first null following the "ARGV=".
  304. It is important not to assume that the null follows immediately after
  305. the "ARGV=", because some implementations may assign a value to the
  306. ARGV environment variable.  After setting up an array of pointers to the
  307. arguments, the startup code should set the 'A' of the "ARGV" variable
  308. to null, thus separating the environment from the argument strings
  309. (remember: a double null terminates the environment).
  310.  
  311. Here is some example C startup code which shows how a child could
  312. look for arguments in its environment:
  313.  
  314. * ARGSTART.S - example C startup code
  315. * using GEMDOS Extended Argument Specification
  316. * ================================================================
  317. * 890910 kbad
  318.  
  319. .globl          _main           ; external, C entry point
  320. .globl          _argv0          ; external, name used for argv[0] if no ARGV
  321. .globl          _stksize        ; external, size of application stack
  322. .globl          _basepage       ; allocated here, -> program's basepage
  323. .globl          _environ        ; allocated here, -> envp[]
  324. .globl          _argvecs        ; allocated here, -> argv[]
  325. .globl          _stklimit       ; allocated here, -> lower limit of stack
  326. .BSS
  327. _basepage:      ds.l    1
  328. _environ:       ds.l    1
  329. _argvecs:       ds.l    1
  330. _stklimit:      ds.l    1
  331. .TEXT
  332. _start:
  333.         move.l  4(sp),a5        ; get basepage
  334.         move.l  a5,_basepage    ; save it
  335.         move.l  24(a5),a0       ; bss base
  336.         add.l   28(a5),a0       ; plus bss size = envp[] base
  337.         move.l  a0,_environ     ; save start of envp[]
  338.         move.l  a0,a1           ; start of env/arg vectors
  339.         move.l  44(a5),a2       ; basepage environment pointer
  340.         tst.b   (a2)            ; empty environment?
  341.         beq.s   nargv           ; yes, no envp[]
  342.  
  343.         lea.l   (sp),a4         ; use dummy return pc on stack for ARGV test
  344. * --- fill in the envp[] array
  345. nxenv:  move.l  a2,(a1)+        ; envp[n]
  346.         move.l  a2,a3
  347. nxen1:  tst.b   (a2)+
  348.         bne.s   nxen1           ; get the end of this variable
  349.         tst.b   (a2)            ; end of env?
  350.         beq.s   xenv
  351. * --- check for ARGV
  352.         move.b  (a3)+,-(a4)     ; get 1st 4 bytes of this var
  353.         move.b  (a3)+,-(a4)
  354.         move.b  (a3)+,-(a4)
  355.         move.b  (a3)+,-(a4)
  356.         cmp.l   #'VGRA',(a4)+   ; is it ARGV?
  357.         bne.s   nxenv
  358.         cmp.b   #'=',(a3)       ; is it ARGV=?
  359.         bne.s   nxenv
  360.         clr.b   -4(a3)          ; ARGV marks the end of our environment
  361.         cmp.b   #127,$80(a5)    ; command line validation?
  362.         bne.s   nargv           ; nope... and we're done with the env.
  363. * --- got an ARGV=, create argv[] array
  364.         clr.l   (a1)+           ; terminate envp[]
  365.         move.l  a1,_argvecs     ; save base of argv[]
  366. nxarg:  move.l  a2,(a1)+        ; argv[n]
  367. nxar1:  tst.b   (a2)+
  368.         bne.s   nxar1
  369.         tst.b   (a2)
  370.         bne.s   nxarg
  371. * --- end of environment
  372. xenv:   move.l  _argvecs,d0     ; if we got an argv[]
  373.         bne.s   argok           ; don't parse command tail
  374. * --- No ARGV, parse the command tail
  375. * NOTE: This code parses the command tail IN PLACE.  This can cause problems
  376. *       because the default DTA set up by GEMDOS for a program is located
  377. *       in the command tail part of the basepage.  You should use Fsetdta()
  378. *       to set up your own DTA before performing any operations which could
  379. *       use the DTA if you want to preserve the arguments in the command tail.
  380. nargv:  clr.l   (a1)+           ; terminate envp[]
  381.         move.l  a1,_argvecs     ; base of argv[]
  382.         move.l  #_argv0,(a1)+   ; default name for argv[0]
  383.         lea     128(a5),a2      ; command tail
  384.         move.b  (a2)+,d2        ; length byte
  385.         ext     d2
  386.         moveq   #125,d1         ; validate length
  387.         cmp     d1,d2
  388.         bcs.s   valen
  389.         move    d1,d2           ; if invalid length, copy all of tail
  390. valen:  clr.b   0(a2,d2)        ; null tail because desktop inserts <cr>
  391.         moveq   #' ',d1         ; space terminator
  392. get1:   move.b  (a2)+,d2        ; null byte?
  393.         beq.s   argok           ; if so, we're done
  394.         cmp.b   d1,d2           ; strip leading spaces
  395.         beq.s   get1
  396.         subq    #1,a2           ; unstrip start char
  397.         move.l  a2,(a1)+        ; and store that arg
  398. get2:   move.b  (a2)+,d2        ; next char
  399.         beq.s   argok           ; if null, we're done
  400.         cmp.b   d1,d2           ; if not space...
  401.         bne.s   get2            ; keep looking
  402.         clr.b   -1(a2)          ; terminate argv[argc] in the command tail
  403.         bra.s   get1            ; get next arg
  404. argok:  clr.l   (a1)+           ; terminate argv[]
  405. * --- allocate stack
  406.         move.l  a1,_stklimit    ; end of env/arg vectors is stack limit
  407.         add.l   _stksize,a1     ; allocate _stksize bytes of stack
  408.         move.l  a1,sp           ; set initial stack pointer
  409. * --- release unused memory
  410.         sub.l   a5,a1           ; size to keep
  411.         move.l  a1,-(sp)
  412.         move.l  a5,-(sp)        ; base of block to shrink
  413.         pea     $4a0000         ; Mshrink fn code + junk word of 0
  414.         trap    #1
  415.         lea     12(sp),sp       ; pop args
  416. *
  417. * Everything beyond here depends on implementation.
  418. * At this point, _environ points to envp[], _argvecs points to argv[],
  419. * and _stklimit points to the end of the argv array.  Thus argc can
  420. * be calculated as ((_stklimit-_argvecs)/4)-1.
  421. * _main could be invoked as follows:
  422. *
  423.         move.l  a5,-(sp)        ; basepage
  424.         move.l  _environ,-(sp)  ; envp[]
  425.         move.l  _argvecs,-(sp)  ; argv[]
  426.         move.l  _stklimit,d0    ; 4 bytes past end of argv[]
  427.         sub.l   (sp),d0         ; (argc+1) * sizeof( char * )
  428.         asr.l   #2,d0           ; argc+1
  429.         subq    #1,d0           ; argc
  430.         move    d0,-(sp)
  431.         jsr     _main           ; call mainline
  432.         lea     14(sp),sp       ; pop args
  433.  
  434.  
  435. A Final Note
  436.  
  437. This specification was formulated with careful deliberation, and with
  438. input from several companies and developers who have created
  439. development tools for GEMDOS.  The Mark Williams extended argument
  440. passing scheme was the main influence for this specification, because
  441. it has been in use, and supported by Mark Williams and other companies
  442. for several years.  This specification is very similar to the Mark
  443. Williams scheme, with the following important exceptions:
  444.  
  445. 1) Under the specification, the arguments after the ARGV environment
  446. variable may be validated by checking the command tail length byte.
  447. The Mark Williams execve() library function uses the command tail
  448. length byte as a telltale, but it is not checked by the crts0 startup
  449. code.  This validation is important for the reasons mentioned in the
  450. Rationale section above.
  451.  
  452. 2) The specification allows the ARGV environment variable to take on any
  453. value.  Mark Williams uses the value of ARGV as an iovector, which is
  454. described in the Mark Williams documentation.  The iovector should no
  455. longer be needed, as its primary purpose was to simplify the MWC
  456. implementation of the C library function isatty().
  457.  
  458. 3) Some versions of the MWC startup code do not require the ARGV= to
  459. have an `='.  Because ARGV is an actual environment variable in the
  460. specification, the equals character is required.
  461. --
  462.    |||   Ken Badertscher  (ames!atari!kbad)
  463.    |||   Atari R&D System Software Engine
  464.   / | \  #include <disclaimer>
  465.  
  466. ------------------------------
  467.  
  468. End of INFO-ATARI16 Digest V89 Issue #595
  469. *****************************************
  470.